Correctness fixes, shared view lifecycle, and build gates - #10

…he build

Six tool views each carried their own copy of the same load lifecycle. `activate`,
`_on_data_error`, `on_button_pressed` and `on_select_changed` appeared in all six,
`_populate_filters`, `_apply_filters` and `_fetch_data` in five, and the filter-bar
CSS block in all six; `_on_data_error` was byte-identical everywhere. Duplication
of a decision is duplication of the chance to get it wrong, and three of the six
Refresh buttons did.

─── ToolView ───

src/ffb/ui/base.py holds the lifecycle. A subclass sets ID_PREFIX and LOAD_LABEL
and implements compose_content, fetch and apply; the base owns the thread worker,
the loading pane, error reporting, refresh, filter reading and table rendering.

Refresh is the reason the seam exists. `on_button_pressed` matches the view's
refresh button and always calls the fetch with force_refresh=True. waiver_wire,
start_sit and trade_value had instead reset an activation flag and re-entered
`activate()`, reaching the fetch with force_refresh defaulting to False — so the
button re-read the same cache and reported success, against a README promising a
fresh download. Routing every view through one handler makes the divergence
unrepresentable.

`fill_table` renders an empty frame as a stated message rather than a bare header
over blank space, and reads emptiness from height so a frame carrying no columns at
all cannot raise. All six tools had rendered an empty result identically to a
loading one.

`selected` and `narrowing` collapse the unselected sentinel and the "All"
convention in one place. `Select.BLANK` resolves to the inherited `Widget.BLANK`,
the bool False, so every `is Select.BLANK` guard was dead and every
`not in ("All", Select.BLANK)` was true, letting a NoSelection reach a polars
comparison. `Select.NULL` is the sentinel, and it is reachable from one method.

A load renders once. Select option-setting and value assignment post `Select.Changed`
asynchronously, so a flag cleared when `apply` returns is already clear when those
messages dispatch and each triggers a further filter pass — a full recomputation per
filter in trade_value. The base compares live filter state against what backs the
current render and dispatches only on a real change.

`run_off_thread` owns the worker, the cancellation guard and error routing, so
injury_impact's player search shares the load worker's failure handling.

A long load shows what it is downloading and elapsed time, offers Cancel and binds
escape, and a cancelled load does not render. No percentage is displayed: nflverse
reports no progress, so one would be invented.

─── Data layer ───

loader — one `_cached` helper backs all seven loaders, replacing six copies of the
same cache-check-fetch-store body. Each download runs on its own daemon thread, so
a stalled fetch no longer holds the single shared worker while the next call's
timeout budget runs down against a queue it never left. The weekly-stats fallback
narrows its catch, so a failure that is not data unavailability propagates rather
than silently deriving the season from play-by-play.

cache — parquet and metadata both land through a temporary file and os.replace, so
a crash or a second writer leaves one whole file or the other. A size ceiling
evicts in least-recently-accessed order and orphans are reaped in both directions;
one parquet per season tuple had otherwise accrued without bound against
play-by-play measured in hundreds of megabytes.

seasons — `current_season` and `recent_seasons` resolve the nflverse season label
from an injectable date, replacing thirteen hardcoded season literals across the
six views that needed editing each September.

─── Gates ───

.github/workflows/ci.yml runs lint, format, typecheck, tests with coverage, build,
and a dependency vulnerability scan that fails the build on findings. Installs come
from the committed lockfile, so lockfile drift fails before any gate runs.

pyproject sets mypy `strict = true` with no carve-out, adds ten optional error
codes, and enables `ignore-without-code` and `warn_unused_ignores` so silencing a
check is itself a failure. Coverage measures src/ffb with branch coverage against a
floor taken from measurement.

tests/test_project_gates.py pins the gates against silent relaxation: any boolean
under [tool.mypy] set false fails, since a false there reads as strict while
exempting the check it names.

Views, the base class, both data-layer modules and the app shell gain suites,
driven headlessly through Textual's pilot with the loaders stubbed. The refresh
contract is parametrised across all six views so no tool can regress alone.

Co-authored-by: stxkxsbot <275011021+stxkxsbot@users.noreply.github.com>

…hape

Three documented behaviours did not match the code, and one named file did not
exist. A claim a reader can act on and be wrong about is worse than no claim.

─── Corrections ───

README described the trade-value production component as season PPG times games
remaining, weighted 0.40, alongside a separate 0.10 bye-week penalty. It documents
what the engine computes: production is PPG times per-player games remaining, which
subtracts a bye still ahead, weighted 0.50, with no standalone bye term.

README's injury-impact bullets keyed the confidence tier to a generic sample size
and named the wrong season window. Both are read from the engine and the view.

CLAUDE.md listed `nfl.import_player_stats`, which the installed nfl_data_py does
not export. The importer list names the seven the loaders call, each of which
resolves.

CLAUDE.md pointed at `nfl-data-api-research.md` for API research and decision
rationale. No such file is in the repository. The supplementary-API content it
promised already sits inline in CLAUDE.md, so the dangling pointer is removed
rather than satisfied with invented research.

─── Additions ───

README gains Configuration, Troubleshooting and Development sections. The first run
of any tool is a multi-minute download of two seasons of play-by-play, so
Troubleshooting names the elapsed-time readout, the Cancel button and escape
binding, the per-download timeout and what its failure means. Configuration states
the cache location, its TTL and its size ceiling, each read from the source.

docs/architecture.md explains the shape a contributor needs and the code cannot
state for itself: why each tool is a bounded context split into a pure engine and a
Textual view, why engines take frames and return frames with no I/O, what ToolView
owns against what a view owns, how the cache and loader sit underneath, and what
adding a seventh tool involves.

Co-authored-by: stxkxsbot <275011021+stxkxsbot@users.noreply.github.com>